Codex 1UP: Supercharge Codex CLI for Real‑World Coding
This guide is for developers already using Codex to code. In 10 minutes, turn your local terminal into an AI pair‑programmer that can read, edit, and run your project — powered by a practical toolchain for structural refactors and semantic diffs.

Why Codex 1UP?
Section titled “Why Codex 1UP?”Codex 1UP is a one‑tap booster for the official OpenAI Codex CLI. It adds the missing “peripherals” developers reach for daily: structural search/replace, semantic diffs, fast file/text search, fuzzy picking, JSON/YAML tooling — plus a ready‑to‑use AGENTS.md and shell aliases. The goal is simple: make local Codex more practical and reliable. It’s actively updated on GitHub and supports macOS/Linux (Windows recommended via WSL).
What it brings:
- Installs Codex CLI (@openai/codex) so you can ask an AI to read, edit, and run in your repo.
- Adds ast‑grep for syntax‑tree aware refactors — much sturdier than plain text grep.
- Adds difftastic for semantic diffs to review AI edits with less noise (falls back to delta if needed).
- Bundles fd / ripgrep / fzf / jq / yq for fast file finding, text search, fuzzy select, and JSON/YAML ops.
- Includes AGENTS.md templates and SAFE/DEFAULT/YOLO profiles so teams can standardize how AI uses tools.
Who is it for?
Section titled “Who is it for?”- Safe refactors in large monorepos: Plan first with Codex, apply with ast‑grep, review with difftastic.
- Inheriting legacy code:
rgmaps call sites in seconds;fdfinds files faster thanfind;fzfnarrows targets interactively. - Compliance‑minded workflows: Choose SAFE/DEFAULT to gate over‑privileged actions and network; switch to YOLO when you truly trust the sandbox.
- Teams that want shared rules: The AGENTS.md template documents “use fd/rg first; fzf to narrow; structural edits via ast‑grep”.
Highlights at a glance
Section titled “Highlights at a glance”- Read‑Edit‑Run: Codex CLI runs locally with ChatGPT sign‑in, can read files, apply patches, and execute tasks.
- Structural refactors:
ast-grep -p 'old()' -r 'new()'— patterns that read like code. - Semantic review:
cxdiffleverages difftastic to focus on meaningful changes. - Search & select:
rgfor text,fdfor files,fzfto pick,jq/yqfor JSON/YAML.
Install walkthrough (based on your dry‑run)
Section titled “Install walkthrough (based on your dry‑run)”Dry‑run output below (prints actions without changing the system):
git clone https://github.com/openai/codex-1up.git
cd codex-1up
./install.sh --dry-run==> codex-1up installerLog: /Users/vs/.codex-1up/install-20250910-174058.log✔ Node.js present (v22.11.0)Checking global npm packages (@openai/codex, @ast-grep/cli)✔ @openai/codex up-to-date (0.31.0)✔ @ast-grep/cli up-to-date (0.39.5)✔ Global npm packages are up-to-date✔ Codex CLI installed✔ ast-grep installedDetected package manager: brew[dry-run] brew update[dry-run] brew install fd ripgrep fzf jq yq difftastic⚠ difftastic not found and Rust/cargo missing; falling back to git-delta✔ rg ✓✔ jq ✓✔ ast-grep ✓Configure git diff tools for better syntax-aware code diffs (recommended for developers)? [y/N] yConfiguring git difftool aliases⚠ No difftastic or delta found; git diff will remain defaultThe following aliases will be added to /Users/vs/.zshrc: cx='codex exec' # Run codex commands cxdiff='git difftool -y' # Launch git difftool fd='fdfind' # fd-find alias (if applicable)Add these aliases to your shell config? [y/N] yUpdating shell rc: /Users/vs/.zshrc[dry-run] append block to /Users/vs/.zshrcChoose your codex-1up configuration profile:
1) SAFE - Most restrictive, asks for approval when commands fail (Recommended for high-security environments)
2) DEFAULT - Balanced approach, asks for approval when needed (Recommended for most users - good security/usability balance)
3) YOLO - Full access, never asks for approval ⚠️ WARNING: Allows codex full disk + network access! ⚠️ WARNING: Inherits ALL environment variables (including secrets)! ⚠️ Only use in trusted, sandboxed environments!
4) NO CHANGES - Do not create or modify ~/.codex/config.toml (You can manage it yourself later)Choose profile [1-4] (default: 2/DEFAULT): 2⚠ ~/.codex/config.toml already existsOverwrite with the 'default' template? (existing will be backed up) [y/N] y[dry-run] cp /Users/vs/.codex/config.toml /Users/vs/.codex/config.toml.backup.20250910_174210Backed up existing config to: /Users/vs/.codex/config.toml.backup.20250910_174210Creating config using default profile[dry-run] cp /Users/vs/WorkSpaces/VibeSparking/github/regenrek/codex-1up/templates/configs/codex-default.toml /Users/vs/.codex/config.toml✔ Created ~/.codex/config.toml with default profileSee config options: https://github.com/openai/codex/blob/main/docs/config.mdDo you want to create a global AGENTS.md for personal guidance at ~/.codex/AGENTS.md?
1) default - Generic rubric (works for most repos) 2) typescript - TS/TSX-focused rubric with ast-grep examples 3) python - Python-focused rubric and tooling notes (ruff, mypy, pytest) 4) shell - Shell/Bash-focused rubric with shellcheck/shfmt/bats tips 5) NONE - Do not create ~/.codex/AGENTS.mdChoose template [1-5] (default: 5/NONE): 1Writing global AGENTS.md to: /Users/vs/.codex/AGENTS.md (template: default)[dry-run] cp /Users/vs/WorkSpaces/VibeSparking/github/regenrek/codex-1up/templates/agent-templates/AGENTS-default.md /Users/vs/.codex/AGENTS.md✔ Wrote /Users/vs/.codex/AGENTS.mdVS Code extension id not provided. Use: --vscode <publisher.extension>✔ All done. Open a new shell or 'source' your rc file to load aliases.Next steps: 1) codex # sign in; then ask it to plan a refactor 2) ./bin/codex-1up agents --path /Users/vs/WorkSpaces/VibeSparking/github/regenrek/codex-1up # write a starter AGENTS.md to your repo 3) Review ~/.codex/config.toml (see: https://github.com/openai/codex/blob/main/docs/config.md)Key takeaways:
- Node/global checks: Verifies Node 22 and versions of
@openai/codexand@ast-grep/cli— you’re up to date. Codex CLI is the official local coding agent. - Package manager = Homebrew: Plans to install
fd / ripgrep / fzf / jq / yq / difftasticfor files, text, fuzzy pick, JSON, YAML, semantic diff. - Difftastic note: Without Rust/cargo, falls back to git‑delta; in dry‑run it only prints. Difftastic is syntax‑aware diff.
- Git difftool + aliases:
cxdiffrunsgit difftool -y;cxiscodex exec— handy for batch edits and runs. - Profile choice: You chose DEFAULT: balanced mode — read/edit/run locally; prompts on over‑privileged or network actions. Pick SAFE for tighter controls; YOLO when you accept the risks.
- Backups +
~/.codex/config.toml: Uses a template you can tweak anytime. Official docs recommend signing in viacodexfirst. - Global
~/.codex/AGENTS.md: The default template gives Codex practical guidance for choosing tools. - Next steps: Open a new shell or
source ~/.zshrc→ runcodexto sign in → generate a repo‑level AGENTS.md when ready.
Tip: On Windows, prefer WSL. Windows support is best via WSL today.
Five quick moves (copy‑ready)
Section titled “Five quick moves (copy‑ready)”-
Let Codex plan before it edits
codex "Plan a refactor to replace axios with fetch; then apply and run tests" -
Structural replace (TypeScript example)
ast-grep -p "oldApi($A)" -r "newApi($A)" src --lang ts -
Find call sites fast
rg "useAuth(" -n/fd "auth*.ts"— faster and sharper than plaingit grep. -
Review with semantic diff
cxdiffopens difftastic (if installed) for meaningful changes. -
Batch config work
jq '.scripts' package.json/yq '.services[].image' docker-compose.yml.
Risks and best practices
Section titled “Risks and best practices”- YOLO is powerful — and risky: It unlocks read/write + network. Avoid on machines with sensitive env vars.
- Review large changes: Use
cxdiffand tests; split into smaller PRs when needed. - Tune AGENTS.md to your repo: Provide do/don’t examples; note when to prefer ast‑grep vs. “plan‑only” reads.
Conclusion
Section titled “Conclusion”Codex 1UP = Local Codex + a structural toolchain.
Code faster, refactor safer, review clearer.
If you’re introducing AI pairing to your team, this combo is worth installing today.
What tools do you rely on most? Any near‑miss saved by ast‑grep or difftastic? Share your stories in the comments.


































































































































































